Skip to content

Commit 8712fa0

Browse files
NikitasT2003NikitasT2003
committed
chore: code quality hardening, docs accuracy, repo hygiene
- Fix 103 ruff lint errors (0 remaining) - Fix bare except bugs in query.py, server.py - Remove unused variable in server.py - Move pytest/responses to dev dependency-group - Add PyPI metadata: keywords, classifiers, project.urls - Fix CHANGELOG: remove false FastAPI claim, add missing commands - Add PR template, SECURITY.md - Update .gitignore, remove generated ruff.json - Remove social_kit.md from tracking - CI: target main branch instead of master - All 25 tests passing
1 parent ee5280e commit 8712fa0

32 files changed

Lines changed: 348 additions & 602 deletions

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
## Description
2+
3+
<!-- What does this PR do? Link to the related issue if applicable. -->
4+
5+
Closes #
6+
7+
## Type of Change
8+
9+
- [ ] 🐛 Bug fix (non-breaking change that fixes an issue)
10+
- [ ] 🚀 New feature (non-breaking change that adds functionality)
11+
- [ ] 🔌 New plugin (framework analyzer plugin)
12+
- [ ] 📝 Documentation update
13+
- [ ] ♻️ Refactor (no functional changes)
14+
- [ ] ⚠️ Breaking change (fix or feature that would break existing behavior)
15+
16+
## Checklist
17+
18+
- [ ] I've run `uv run ruff check .` and there are no lint errors.
19+
- [ ] I've run `uv run pytest` and all tests pass.
20+
- [ ] I've added tests for new functionality.
21+
- [ ] I've updated documentation if needed.
22+
- [ ] The commit messages follow conventional commits style.

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@ name: CI
22

33
on:
44
push:
5-
branches: [ master ]
5+
branches: [ main ]
66
pull_request:
7-
branches: [ master ]
7+
branches: [ main ]
88

99
jobs:
1010
test:

‎.gitignore‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,15 @@ wheels/
1515
# Virtual environments
1616
.venv/
1717

18-
# PRD
18+
# Ruff
19+
.ruff_cache/
20+
ruff.json
21+
ruff_output.txt
22+
23+
# Internal docs (not public)
1924
prd.md
2025
marketing-plan.md
26+
social_kit.md
27+
28+
# Agent skills (local development)
2129
.agents/

‎CHANGELOG.md‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,21 @@
22

33
All notable changes to `agentsrc-py` will be documented in this file.
44

5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
58
---
69

710
## [0.1.0] - 2026-04-07
811
### Added
9-
- **Core Analyzer**: AST-based extraction of functions, classes, and decorators.
10-
- **Project Resolver**: Sync dependencies from active `venv` and `uv.lock`.
11-
- **Framework Support**: initial plugins for **FastAPI** and **Pydantic v2**.
12-
- **Agent Instruction Layer**: Generation of `AGENTS.md` and `instructions.md`.
13-
- **CLI**: Rich-powered interface with `init`, `sync`, and `query` commands.
14-
- **Documentation**: Premium README, Roadmap, and Code of Conduct.
12+
- **Core Analyzer**: AST-based extraction of functions, classes, decorators, and exceptions.
13+
- **Project Resolver**: Sync dependencies from active `venv`, `uv.lock`, `pyproject.toml`, and `requirements.txt`.
14+
- **Framework Plugin**: Initial plugin for **Pydantic v2** model detection.
15+
- **Agent Instruction Layer**: Generation of `instructions.md` and `sources.json` manifests.
16+
- **CLI**: Rich-powered interface with `init`, `sync`, `inject`, `inspect`, and `query` commands.
17+
- **Query Server**: Local HTTP API for symbol search across indexed packages.
18+
- **Content-Addressed Cache**: Deterministic artifact storage with SHA-256 hash verification.
19+
- **Documentation**: Premium README, Roadmap, Contributing guide, and Code of Conduct.
1520

1621
### Initial Release
1722
*Project bootstrapped with a focus on narrowing the agent hallucination gap.*

‎README.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# 📡 agentsrc-py
2-
2+
<p align="center">
3+
<img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python Version">
4+
<img src="https://img.shields.io/badge/build-passing-brightgreen.svg" alt="Build Status">
5+
<img src="https://img.shields.io/badge/license-MIT-orange.svg" alt="License">
6+
<img src="https://img.shields.io/badge/DX-uv%20ready-blueviolet" alt="uv Ready">
7+
<img src="https://img.shields.io/badge/AI-Agent%20Compatible-black" alt="AI Agent Compatible">
8+
</p>
39
<p align="center">
410
<img src="assets/banner.png" alt="agentsrc-py banner" width="800px">
511
</p>
@@ -8,19 +14,13 @@
814
<b>Semantic Signal Extraction for the Age of AI Agents.</b>
915
</p>
1016

11-
<p align="center">
12-
<img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python Version">
13-
<img src="https://img.shields.io/badge/build-passing-brightgreen.svg" alt="Build Status">
14-
<img src="https://img.shields.io/badge/license-MIT-orange.svg" alt="License">
15-
<img src="https://img.shields.io/badge/DX-uv%20ready-blueviolet" alt="uv Ready">
16-
<img src="https://img.shields.io/badge/AI-Agent%20Compatible-black" alt="AI Agent Compatible">
17-
</p>
17+
1818

1919
---
2020

2121
## 👁️ Grounding AI Agents in Reality
2222

23-
Most AI coding agents (Claude, GPT-4, Cursor) understand Python libraries through outdated training data, static docstrings, or high-level type hints. When they encounter undocumented behavior, internal exception flows, or complex framework patterns (Pydantic, FastAPI), **they hallucinate.**
23+
Most AI coding agents (Claude, Cursor, etc.) understand Python libraries through outdated training data, static docstrings, or high-level type hints. When they encounter undocumented behavior, internal exception flows, or complex framework patterns (Pydantic, FastAPI), **they hallucinate.**
2424

2525
`agentsrc-py` bridges this gap. It fetches, unpacks, and performs **AST-level analysis** on the exact version of the dependencies you are using, exposing the "ground truth" of the source code directly to your agent.
2626

‎SECURITY.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Security Policy
2+
3+
## Supported Versions
4+
5+
| Version | Supported |
6+
| :------ | :----------------- |
7+
| 0.1.x | ✅ Current release |
8+
9+
## Reporting a Vulnerability
10+
11+
If you discover a security vulnerability in `agentsrc-py`, please report it responsibly.
12+
13+
**Do NOT open a public GitHub issue for security vulnerabilities.**
14+
15+
Instead, please email: **[tsoumasnikitas@gmail.com](mailto:tsoumasnikitas@gmail.com)**
16+
17+
Include:
18+
- A description of the vulnerability
19+
- Steps to reproduce
20+
- Potential impact
21+
- Suggested fix (if any)
22+
23+
We will acknowledge receipt within **48 hours** and aim to release a fix within **7 days** for critical issues.
24+
25+
## Scope
26+
27+
`agentsrc-py` operates locally and fetches package artifacts from PyPI. Security considerations include:
28+
29+
- **Archive extraction**: The tool unpacks `tar.gz` and `.whl` files. We use Python's standard `tarfile` and `zipfile` modules.
30+
- **Network requests**: HTTP requests are made to `pypi.org` only. No user data is transmitted.
31+
- **Local file writes**: Output is written exclusively to `.agentsrc/` within the project directory.
32+
- **No telemetry**: The tool does not collect or send any usage data.

‎pyproject.toml‎

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,65 @@
11
[project]
22
name = "agentsrc"
33
version = "0.1.0"
4-
description = "Extract semantic signals for AI Agents from Python dependencies."
4+
description = "Fetch exact Python dependency source & extract AST-level semantic signals for AI coding agents."
55
readme = "README.md"
6+
license = "MIT"
67
authors = [
78
{ name = "NikitasT2003", email = "tsoumasnikitas@gmail.com" }
89
]
910
requires-python = ">=3.11"
11+
keywords = [
12+
"ai-agents",
13+
"ast",
14+
"coding-assistant",
15+
"developer-tools",
16+
"llm",
17+
"pypi",
18+
"python",
19+
"semantic-analysis",
20+
"source-code",
21+
]
22+
classifiers = [
23+
"Development Status :: 3 - Alpha",
24+
"Intended Audience :: Developers",
25+
"License :: OSI Approved :: MIT License",
26+
"Programming Language :: Python :: 3",
27+
"Programming Language :: Python :: 3.11",
28+
"Programming Language :: Python :: 3.12",
29+
"Programming Language :: Python :: 3.13",
30+
"Topic :: Software Development :: Libraries",
31+
"Topic :: Software Development :: Quality Assurance",
32+
"Typing :: Typed",
33+
]
1034
dependencies = [
1135
"pydantic>=2.12.5",
1236
"pydantic-settings>=2.13.1",
13-
"pytest>=9.0.2",
1437
"requests>=2.33.1",
15-
"responses>=0.26.0",
1638
"rich>=14.3.3",
1739
"typer>=0.24.1",
1840
]
1941

42+
[dependency-groups]
43+
dev = [
44+
"pytest>=9.0.2",
45+
"responses>=0.26.0",
46+
"ruff>=0.11.0",
47+
]
48+
49+
[project.urls]
50+
Homepage = "https://github.com/NikitasT2003/agentsrc-py"
51+
Repository = "https://github.com/NikitasT2003/agentsrc-py"
52+
Issues = "https://github.com/NikitasT2003/agentsrc-py/issues"
53+
Changelog = "https://github.com/NikitasT2003/agentsrc-py/blob/main/CHANGELOG.md"
54+
2055
[tool.pytest.ini_options]
2156
testpaths = ["tests"]
2257
python_files = "test_*.py"
2358
norecursedirs = [".*", "build", "dist"]
2459

2560
[tool.ruff]
2661
line-length = 100
27-
target-version = "py312"
62+
target-version = "py311"
2863

2964
[tool.ruff.lint]
3065
select = ["E", "F", "I", "W"]

0 commit comments

Comments
 (0)