{"id":30288399,"url":"https://github.com/defcon-007/portia-fastapi-example","last_synced_at":"2025-08-16T22:36:41.139Z","repository":{"id":303448261,"uuid":"1015463450","full_name":"DefCon-007/portia-fastapi-example","owner":"DefCon-007","description":"A FastAPI application integrated with the Portia SDK for building agentic workflows.","archived":false,"fork":false,"pushed_at":"2025-07-07T16:46:30.000Z","size":172,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-07T18:08:20.919Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DefCon-007.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-07T14:37:50.000Z","updated_at":"2025-07-07T16:46:33.000Z","dependencies_parsed_at":"2025-07-07T18:08:30.866Z","dependency_job_id":"799e5180-1b5f-4414-98a7-e159e46cfd2d","html_url":"https://github.com/DefCon-007/portia-fastapi-example","commit_stats":null,"previous_names":["defcon-007/portia-fastapi-example"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DefCon-007/portia-fastapi-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DefCon-007%2Fportia-fastapi-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DefCon-007%2Fportia-fastapi-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DefCon-007%2Fportia-fastapi-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DefCon-007%2Fportia-fastapi-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DefCon-007","download_url":"https://codeload.github.com/DefCon-007/portia-fastapi-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DefCon-007%2Fportia-fastapi-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270781211,"owners_count":24643807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-16T22:36:34.489Z","updated_at":"2025-08-16T22:36:41.127Z","avatar_url":"https://github.com/DefCon-007.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Portia FastAPI Example\n\nA well-structured FastAPI application integrated with the Portia SDK for building agentic workflows. This project demonstrates FastAPI best practices including proper async handling, Pydantic settings management, and clean architecture.\n\n## Features\n\n- 🚀 **FastAPI** with async support and modern Python features\n- 🔧 **Portia SDK** integration for agentic workflows\n- ⚙️ **Pydantic Settings** for configuration management\n- 📊 **Structured logging** with configurable levels\n- 🔍 **Health checks** and monitoring endpoints\n- 📚 **Auto-generated OpenAPI documentation**\n- 🐳 **Production-ready** with proper error handling\n- ⚡ **UV** for fast dependency management and project tooling\n\n## Project Structure\n\n```\nportia-python-fastapi-example/\n├── app/\n│   ├── __init__.py\n│   ├── main.py                 # FastAPI application setup\n│   ├── config.py               # Pydantic settings and configuration\n│   ├── exceptions.py           # Custom exceptions\n│   ├── api/\n│   │   ├── __init__.py\n│   │   ├── health.py           # Health check endpoints\n│   │   └── run.py              # Main API endpoints\n│   ├── schemas/\n│   │   ├── __init__.py\n│   │   ├── health.py           # Health check schemas\n│   │   └── run.py              # Run endpoint schemas\n│   └── services/\n│       ├── __init__.py\n│       └── portia_service.py   # Portia SDK integration\n├── pyproject.toml              # Project configuration\n├── README.md\n└── LICENSE\n```\n\n## Installation\n\n1. **Clone the repository:**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd portia-python-fastapi-example\n   ```\n\n2. **Install [UV](https://docs.astral.sh/uv/) (if not already installed):**\n   ```bash\n   curl -LsSf https://astral.sh/uv/install.sh | sh\n   ```\n\n3. **Install dependencies:**\n   ```bash\n   uv sync\n   ```\n\n## Environment Setup\n\n1. **Set up environment variables:**\n   Create a `.env` file in the root directory with at least one api key:\n   ```env\n   # LLM Settings (at least one is required)\n   OPENAI_API_KEY=\"your-openai-api-key\"\n   ANTHROPIC_API_KEY=\"your-anthropic-api-key\"\n   ```\n\n## Usage\n\n### Running the Application\nThis will start the FastAPI server locally in dev mode.\n\n```bash\nuv run fastapi dev main.py\n```\n\n### Using the Dockerfile\n\n1. Build the docker image\n    ```bash\n    docker build -t portia-fastapi-example .\n    ```\n\n2. Run the docker image\n    ```bash\n    docker run -p 8000:8000 \\\n      -e OPENAI_API_KEY=\"your-openai-key\" \\\n      -e DEBUG=\"false\" \\\n      portia-fastapi-example\n    ```\n\n### API Documentation\n\nOnce the application is running, you can access:\n\n- **Interactive Swagger UI API docs**: http://localhost:8000/docs\n- **API docs (ReDoc)**: http://localhost:8000/redoc\n- **OpenAPI JSON**: http://localhost:8000/openapi.json\n\n## API Endpoints\n\n### GET /\n\nWelcome endpoint that returns basic application information.\n\n**Response:**\n```json\n{\n  \"message\": \"Welcome to Portia FastAPI Example\",\n  \"version\": \"0.1.0\",\n  \"docs_url\": \"/docs\"\n}\n```\n\n### POST /run\n\nExecute a query using the Portia SDK.\n\n**Request:**\n```json\n{\n  \"query\": \"What is 2+2?\",\n  \"tools\": [\"calculator_tool\"]\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"result\": {\n    \"value\": \"4.0\",\n    \"summary\": \"The query asked for the result of 2+2, and the expression was evaluated to give the output 4.0.\"\n  },\n  \"error\": null,\n  \"execution_time\": 2.5\n}\n```\n\n### GET /tools\n\nGet available tools from the Portia SDK.\n\n**Response:**\n```json\n[\"calculator_tool\", \"search_tool\", \"weather_tool\"]\n```\n\n### GET /health\n\nHealth check endpoint.\n\n**Response:**\n```json\n{\n  \"status\": \"healthy\",\n  \"version\": \"0.1.0\"\n}\n```\n\n## Configuration\n\nThe application uses Pydantic Settings for configuration management. Settings can be configured via:\n\n1. **Environment variables**\n2. **`.env` file**\n3. **Default values**\n\n### Available Settings\n\n| Setting               | Default                  | Description               |\n| --------------------- | ------------------------ | ------------------------- |\n| `APP_NAME`            | \"Portia FastAPI Example\" | Application name          |\n| `APPLICATION_VERSION` | \"0.1.0\"                  | Application version       |\n| `DEBUG`               | `false`                  | Debug mode                |\n| `HOST`                | \"127.0.0.1\"              | Server host               |\n| `PORT`                | 8000                     | Server port               |\n| `ALLOWED_DOMAINS`     | `[\"*\"]`                  | CORS allowed domains      |\n| `PORTIA_API_KEY`      | `None`                   | Portia API key (optional) |\n| `OPENAI_API_KEY`      | `None`                   | OpenAI API key            |\n| `ANTHROPIC_API_KEY`   | `None`                   | Anthropic API key         |\n| `LOG_LEVEL`           | \"INFO\"                   | Logging level             |\n\n## Development\n\n### Architecture\n\nThe application follows a clean architecture pattern:\n\n- **API Layer** (`app/api/`): FastAPI route handlers\n- **Service Layer** (`app/services/`): Business logic and external integrations\n- **Schema Layer** (`app/schemas/`): Pydantic models for request/response validation\n- **Configuration** (`app/config.py`): Application settings management\n- **Exception Handling** (`app/exceptions.py`): Custom exceptions\n\n### Running Tests\n\n```bash\n# Install dev dependencies (included with uv sync)\nuv sync --group dev\n\n# Run tests\nuv run pytest\n\n# Run tests with coverage\nuv run pytest --cov=app\n```\n\n### Code Quality\n\nThis project uses `ruff` for linting and formatting:\n\n```bash\n# Run linting\nuv run ruff check .\n\n# Run formatting\nuv run ruff format .\n```\n\n### CI/CD\n\nThis project includes a GitHub Actions workflow (`.github/workflows/ci.yml`) for testing in the CI pipeline as well.\n\nThe workflow is triggered on:\n- Push to `main` branch\n- Pull requests to `main` branch\n\nTo run the same checks locally:\n\n```bash\n# Run all CI checks\nuv run ruff check .\nuv run ruff format --check .\nuv run pytest tests/ -v\n\n# Run tests with coverage\nuv run pytest tests/ --cov=app --cov-report=term-missing\n```\n\n### Adding New Endpoints\n\n1. Create schemas in `app/schemas/`\n2. Add business logic in `app/services/`\n3. Create API routes in `app/api/`\n4. Include the router in `app/main.py`\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests and linting\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the terms specified in the LICENSE file.\n\n## Links\n\n- [FastAPI Documentation](https://fastapi.tiangolo.com/)\n- [Portia SDK Documentation](https://docs.portialabs.ai/)\n- [Pydantic Settings](https://docs.pydantic.dev/latest/usage/settings/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefcon-007%2Fportia-fastapi-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdefcon-007%2Fportia-fastapi-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefcon-007%2Fportia-fastapi-example/lists"}